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Foreword 



This Technical Specification has been produced by the 3"^ Generation Partnership Project (3GPP). 

3GPP acknowledges the contribution of the Parlay X Web Services specifications from The Parlay Group. The Parlay 
Group is pleased to see 3GPP acknowledge and publish the present document, and the Parlay Group looks forward to 
working with the 3GPP community to improve future versions of the present document. 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



The present document is part 10 of a multi-part deliverable covering the 3' Generation Partnership Project; Technical 
Specification Group Core Network; Open Service Access (OSA); Parlay X Web Services, as identified below: 



Part 1 


"Overview and common data definitions" 


Part 2 


"Third party call"; 


Part 3 


"Call Notification"; 


Part 4 


"Short Messaging"; 


Parts 


"Multimedia Messaging"; 


Part 6 


"Payment"; 


Part? 


"Account management"; 


Parts 


"Terminal Status"; 


Part 9 


"Terminal location"; 


Part] 


0: "Call handling"; 


Parti 


1: "Audio call"; 


Parti 


2: "Multimedia conference"; 


Parti 


3: "Address Hst management"; 


Parti 


4: "Presence". 



£75/ 



3GPP TS 29.1 99-1 version 6.1 .0 Release 6 5 ETSI TS 1 29 1 99-1 V6.1 .0 (2005-06) 

1 Scope 

The present document is Part 10 of the Stage 3 Parlay X Web Services specification for Open Service Access (OS A). 

The OS A specifications define an architecture that enables application developers to make use of network functionality 
through an open standardized interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA are 
contained in 3GPP TS 23.127 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the Call Handling Web Service aspects of the interface. All aspects of the Call Handling 
Web Service are defined here, these being: 

Name spaces. 

Sequence diagrams. 

Data definitions. 

Interface specification plus detailed method descriptions. 

Fault definitions. 

Service policies. 

WSDL Description of the interfaces. 

The present document has been defined jointly between 3GPP TSG CT WG5, ETSI TISPAN and The Parlay Group. 

2 References 

The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TR 21.905: "Vocabulai-y for 3GPP Specifications". 

[2] 3GPP TS 22. 127: "Service Requirement for the Open Services Access (OSA); Stage 1 ". 

[3] 3GPP TS 23. 127: "Virtual Home Environment (VHE) / Open Service Access (OSA); Stage 2". 

[4] 3GPP TS 22.101: "Service aspects; Service principles". 

[5] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes". 

NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/ . 

[6] 3GPP TS 29.199-1: "Open Service Access (OSA); Parlay X Web Services; Part 1: Common". 

3 Definitions and abbreviations 
3.1 Definitions 

For the purposes of the present document, the terms and definitions given in 3GPP TS 29.199-1 [6] apply. 
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3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in 3GPP TS 29.199-1 [6] apply. 



Detailed service description 



The Call Handling Web Service provides a mechanism for an application to specify how calls are to be handled for a 
specific number. Call handling includes commonly utilized actions: 

• Call accepting - only accepting calls from a list of numbers. 

• Call blocking - blocking calls if they are on a blocking list. 

• Conditional call forwarding - changing the destination of a call to another number for a specific calling number. 

• Unconditional call forwarding - changing the destination of a call to another number. 

• Play audio - initiate audio with the caller (e.g. an announcement or menu). 

The set of rules are provided to the Web Service which is responsible for establishing the call handling function. Only 
one action is taken for a call, and once this action is started the rules will stop being processed. 

There is a specific order in which these rules are processed, providing a predictable call handling expectation for rules 
provided. The processing is done as follows. 

1) Call accepting determines if the call is accepted or rejected. If the caller is not on the accept list, the call is 
rejected and rule processing ends. 

2) Call blocking determines if the call is rejected. If the caller is on the block list, the call is rejected and rule 
processing ends. 

3) Conditional call forwarding - each calling number that has a specific forwarding instruction is checked, and the 
call is forwarded on a match, and rule processing ends. 

4) Unconditional call forwarding - the called number is changed to the call forwarding number and rule processing 
ends. 

5) Play audio - the call is handled by a voice system, which handles all further processing of the call. Rule 
processing ends when the call is handed off 

6) Continue processing call, to complete call to the original called number. 

If no rules are specified in a particular area, then that step is skipped. If the rule processing ends without any action 
being indicated, then the call will continue to the called number. 

Call Handling provides its function without further interaction with the Application. This is in contrast to the Call 
Notification interfaces which provide notifications to the Application for processing. 



5 Namespaces 

The Call Handling interface uses the namespace: 

http://www.csapi.org/wsdl/parlavx/call handling/v2 1 
The data types are defined in the namespace: 

http://www.csapi.org/schema/parlavx/call handling/v2 1 

The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in 
XML Schema [5]. The use of the name 'xsd' is not semantically significant. 
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6 Sequence diagrams 

6.1 Setup call handling, query and clear rules 

Pattern: Request / Response. 

This sequence shows the apphcation setting up Call Handling with rules to be processed., querying those rules and 
clearing them. 



Application 



Call Handling 



Proj/ision handling for one address 



Configure handling 

I 

< 1 



Provision call handling for group 

^ 



Process groups 



^ 



Configure handling 

1 < 



Results 



Get rules for address 



Rules 



< 



Clear rules for addresses 



Process groups 



^- 



Cliear handling 



^ 



< 



Figure 1 
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7.1 



XML Schema data type definition 



Conditional Forward structure 



Information on handling of forwarding for specific calling numbers. 



Element name 


Element type 


Optional 


Description 


CallingAddress 


xsd;anyURI 


No 


Address that call is placed from 


ForwardingAddress 


xsd:anyURI 


No 


Address to forward call to 


OnBusyAddress 


xsd:anyURI 


No 


If line is busy at forwarding address, forward to this address 


OnNoAnswerAddress 


xsd:anyURI 


No 


If no answer at forwarding address, forward to this address 



7.2 



UnconditionalForward structure 



Information for handling of forwarding unconditionally. 



Element name 


Element type 


Optional 


Description 


ForwardingAddress 


xsd:anyURI 


No 


Address to forward call to 


OnBusyAddress 


xsd:anyURI 


No 


If line is busy at forwarding address, forward to this address 


OnNoAnswerAddress 


xsd:anyURI 


No 


If no answer at forwarding address, forward to this address 



7.3 



InteractionContent enumeration 



The following are the types of content that may be used for user interaction. 



Enumeration 


Description 


Text 


Text to be processed by a Text-To-Speech engine 


VoiceXml 


VoiceXML to be processed by a VoiceXML browser 


Audio 


Audio file to be played by an audio processor 



7.4 Textlnteraction structure 

Information for processing by a text to speech engine. 



Element name 


Element type 


Optional 


Description 


Text 


xsd:string 


No 


Text to play through a Text-To-Speech engine 


Language 


xsd:string 


No 


Language of text 



7.5 



Voicelnteraction union 



For a call that is to be handled by an interactive voice system, the information to provide to that system. 



Element name 


Element type 


Description 


UnionElement 


InteractionContent 


Type of content provided (one of the following) 


Textlnfo 


Textlnteraction 


Announcement to play through a Text-To-Speech engine 


VoiceXml 


xsd:anyURI 


Location of VoiceXIVIL to use in a VoiceXIVIL browser 


Audio 


xsd:anyURI 


Location of audio content (WAV or IVIP3 file) 
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7.6 CallHandlingRules structure 

Structure containing set of rules that are applied when the call is handled. 



Element name 


Element type 


Optional 


Description 


AcceptList 


xsd:anyURI [0. .unbounded] 


Yes 


List of addresses to accept calls from 


BlockList 


xsd:anyURI [0.. unbounded] 


Yes 


List of addresses to block calls from 


ForwardList 


ConditionalForward 
[0.. unbounded] 


Yes 


List of conditional forwarding addresses and 
destinations 


Forward 


UnconditionalForward 


No 


Unconditional call forwarding address 


VoicelnteractionContent 


Voicelnteraction 


No 


Forward call to a user interaction system with 
information on content 



7.7 



SetRulesResult structure 



Result of SetRulesRequest for each address. 



Element name 


Element type 


Optional 


Description 


Address 


xsd:anyURI 


No 


Address to be set 


Successful 


xsd:boolean 


No 


Successfully set rules or not 


Error 


common:ServiceError 


Yes 


Error message if unsuccessful 



8 



Web Service interface definition 



8.1 Interface: CallHandling 



CallHandling provides a rule based processing capability that is accessible to Applications through a set of operations 
that allow definition of discrete rules. 

8.1.1 Operation: SetRules 

Set the call handling rules for an address (the destination for the call). If a set of rules is already in place for any of the 
Address, then this operation will replace the old rules with the set provided in this operation. 

The Address may not specify a group. If a group is specified, a PolicyException will be returned. 



8.1.1.1 



Input message: SetRulesRequest 



Part name 


Part type 


Optional 


Description 


Address 


xsd:anyURI 


No 


Address to handle calls for 


Rules 


CallHandlingRules 


No 


Rules to apply for this address 



8.1.1.2 



Output message: SetRulesResponse 



Part name 


Part type 


Optional 


Description 


None 









8.1.1.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• SVCOOOl: Service error. 

• SVC0002: Invalid input value. 



£75/ 



3GPP TS 29.1 99-1 version 6.1 .0 Release 6 1 ETSI TS 1 29 1 99-1 V6.1 .0 (2005-06) 

PolicyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0006: Groups not allowed. 

8.1.2 Operation: SetRulesForGroup 

Set the call handling rules for multiple addresses (the destination for calls). If a set of rules is already in place for any of 
the Addresses, then this operation will replace the old rules with the set provided in this operation. 

The Addresses may include groups, with members using the 'tel:' and 'sip:' URIs in the manner defined in 
3GPP TS 29. 119-1 [6]. Wildcards may not be used to specify addresses. 



8.1.2.1 



Input message: SetRulesForGroupRequest 



Part name 


Part type 


Optional 


Description 


Addresses 


xsd:anyURI [1.. unbounded] 


No 


Addresses to handle calls for 


Rules 


CallHandlingRules 


No 


Rules to apply for these addresses 



8.1.2.2 



Output message: SetRulesForGroupResponse 



Part name 


Part type 


Optional 


Description 


Result 


SetRulesResult [1 ..unbounded] 


No 


Result of setup for each of addresses provided 



8.1.2.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VCOOO 1 : Service error. 

• SVC0002: InvaUd input value. 

• SVC0004: No vaHd addresses. 

• SVC0006: Invalid group. 
PoHcyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0006: Groups not allowed. 

• POL0007: Nested groups not allowed. 

8.1 .3 Operation: GetRules 

Get the call handling rules for an address (the destination for the call). 

The Address may not specify a group. If a group is specified, a PolicyException will be returned. 



8.1.3.1 



Input message: GetRulesRequest 



Part name 


Part type 


Optional 


Description 


Address 


xsdianyURI 


No 


Address to handle calls for 
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8.1.3.2 



Output message: GetRulesResponse 



Part name 


Part type 


Optional 


Description 


Rules 


CallHandlingRules 


No 


Rules being applied for this address 



8.1.3.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• SVCOOOl: Service error. 

• SVC0002: Invalid input value. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0006: Groups not allowed. 

8.1.4 Operation: ClearRules 

Clear the call handling rules associated with the addresses specified. If no rules have been set for an address, this 
operation silently ignores the request, and does not return an error or fault message. 

The Addresses may include groups, with members using the 'tel:' and 'sip:' URIs in the manner defined in 
3GPP TS 29.199-1 [6]. Wildcards may not be used to specify addresses. 



8.1.4.1 



Input message: ClearRulesRequest 



Part name 


Part type 


Optional 


Description 


Addresses 


xsd:anyURI [1.. unbounded] 


No 


Addresses to clear call handling for 



8.1.4.2 



Output message: ClearRulesResponse 



Part name 


Part type 


Optional 


Description 


None 









8.1 .4.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• SVCOOOl: Service error. 

• SVC0002: Invalid input value. 

• SVC0006: Invalid group. 
PoHcyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0006: Groups not allowed. 

• POL0007: Nested groups not allowed. 



Fault definitions 



No new faults defined for this service. 
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1 Service po icies 


Name 


Type 


Description 


VoiceMailAvailable 


xsd:boolean 


Voice mail available or not 


TextToSpeechAvailable 


xsd:boolean 


Service accepts text as an input for processing with a Text-To-Speech engine 


AudioContentAvailable 


xsd:boolean 


Service accepts audio content for playing with an audio player 


VoiceXmlAvailable 


xsd:boolean 


Service accepts VoiceXML for processing with a VoiceXML browser 


AudioFormatsSupported 


xsd:string 


Comma separated string of audio formats supported (e.g. WAV,MP3,AU) 


GroupSupport 


xsd:boolean 


Groups may be included with addresses 


NestedGroupSupport 


xsd:boolean 


Are nested groups supported in group definitions 
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Annex A (normative): 
WSDL for Call handling 



The document/literal WSDL representation of this interface specification is compliant to 3GPP TS 29.199-1 [6] and is 
contained in text files (contained in archive 29199-10-610-doclit.zip) which accompanies the present document. 
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Annex B (informative): 
Change history 



Change history 


Date 


TSG# 


TSG Doc. 


CR 


Rev 


Subject/Comment 


Old 


New 


Sep 2004 


CN 25 


NP-040360 


-- 


-- 


Draft v1 00 submitted to TSG CN#25 for Approval. 


1.0.0 


6.0.0 


Jun 2005 


CT 28 


CP-050221 


0001 


-- 


Optionals for Part 1 


6.0.0 


6.1.0 
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